home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d18
/
tools4c.arc
/
REFMAN.TXT
< prev
next >
Wrap
Text File
|
1988-12-27
|
52KB
|
1,300 lines
TOOLS FOR C
Application Development Package
FUNCTION
REFERENCE MANUAL
Shareware Distribution Version 1.0
This version of TOOLS FOR C and it's associated manuals and
support files may be freely copied and distributed as long as
it is distributed in it's entirety and no fees other than
nominal handling fees are charged. The routines in this
library are NOT Public Domain. This is copyrighted material.
The intent behind distributing this version of TOOLS FOR C is
to allow you to use the package on a trial basis and determine
if it meets your needs. If you find yourself using this
package, you MUST register by sending $45.00 to the address
listed below. Upon receipt of your registration fee we will
send you an expanded manual, compiled libraries for all of the
memory models available with your compiler, and the complete
source code to the library. In NO EVENT may you use any of the
routines in TOOLS FOR C for commercial purposes until you
register your copy. We feel that you will find the value of
TOOLS FOR C far exceeds the registration fee and we at BP
SOFTWARE SOLUTIONS, INC. thank you in advance for your
support.
BP Software Solutions, Inc.
642 N. Commodore Drive
Plantation, Fl. 33325
Copyright (C) 1987
BP Software Solutions Inc.
All Rights Reserved
page 2
Table of Contents
Screen and Cursor Control . . . . . . . . 4
cls() . . . . . . . . . . . . . . . . 4
cursor() . . . . . . . . . . . . . . 4
curs() . . . . . . . . . . . . . . . 4
get_curs() . . . . . . . . . . . . . 4
get_cursor() . . . . . . . . . . . . 4
cursor_type() . . . . . . . . . . . . 5
normal_cursor() . . . . . . . . . . . 5
block_cursor() . . . . . . . . . . . 5
scroll() . . . . . . . . . . . . . . 5
Keyboard Functions . . . . . . . . . . . . 6
key() . . . . . . . . . . . . . . . . 6
shift_stat() . . . . . . . . . . . . 6
char_waiting() . . . . . . . . . . . 6
Character Output . . . . . . . . . . . . . 7
write_a() . . . . . . . . . . . . . . 7
write_am() . . . . . . . . . . . . . 7
write_ac() . . . . . . . . . . . . . 7
write_al() . . . . . . . . . . . . . 7
write_tty() . . . . . . . . . . . . . 8
write_str() . . . . . . . . . . . . . 8
print_string() . . . . . . . . . . . 8
aprintf() . . . . . . . . . . . . . . 8
String Functions . . . . . . . . . . . . . 9
delete_leading() . . . . . . . . . . 9
del_lead_wht() . . . . . . . . . . . 9
delete_trailing() . . . . . . . . . . 9
del_trl_wht() . . . . . . . . . . . . 9
right_just_str() . . . . . . . . . . 9
left_just_str() . . . . . . . . . . . 10
center_str() . . . . . . . . . . . . 10
insert_str() . . . . . . . . . . . . 10
Video Routines . . . . . . . . . . . . . . 11
vid_type() . . . . . . . . . . . . . 11
save_scn() . . . . . . . . . . . . . 11
rest_scn() . . . . . . . . . . . . . 12
video_on() . . . . . . . . . . . . . 12
video_off() . . . . . . . . . . . . . 12
change_att() . . . . . . . . . . . . 12
h_line() . . . . . . . . . . . . . . 13
v_line() . . . . . . . . . . . . . . 13
vert_line() . . . . . . . . . . . . . 13
shuffle_image() . . . . . . . . . . . 14
draw_box() . . . . . . . . . . . . . 14
draw_ex_box() . . . . . . . . . . . . 14
fill_area() . . . . . . . . . . . . . 15
fill_box() . . . . . . . . . . . . . 15
set_vid_mode() . . . . . . . . . . . 15
get_vid_mode() . . . . . . . . . . . 15
page 3
Window Related Functions . . . . . . . . . 16
open_window() . . . . . . . . . . . . 16
open_ex_window() . . . . . . . . . . 16
close_window() . . . . . . . . . . . 16
clear_window() . . . . . . . . . . . 16
activate() . . . . . . . . . . . . . 17
create_window() . . . . . . . . . . . 17
title_window() . . . . . . . . . . . 18
clear_wndw_title() . . . . . . . . . 18
scroll_window() . . . . . . . . . . . 18
cursor_window() . . . . . . . . . . . 19
move_window() . . . . . . . . . . . . 19
wprint_string() . . . . . . . . . . . 19
wprint_string_att() . . . . . . . . . 19
wprintf() . . . . . . . . . . . . . . 20
fprint_window() . . . . . . . . . . . 20
fill_window() . . . . . . . . . . . . 20
Menu Routines . . . . . . . . . . . . . . 21
menu() . . . . . . . . . . . . . . . 21
Data Entry Functions . . . . . . . . . . . 23
get_field() . . . . . . . . . . . . . 23
edit_field() . . . . . . . . . . . . 23
update_ins_flag() . . . . . . . . . . 24
Index . . . . . . . . . . . . . . . . . . 25
page 4
Screen and Cursor Control
FUNCTION NAME: cls()
SYNOPSIS: void cls();
DESCRIPTION:
This function clears the screen and homes the cursor.
FUNCTION NAME: cursor()
curs()
SYNOPSIS: void cursor(col, row)
int col;
int row;
void curs(pos)
int pos;
DESCRIPTION:
These functions place the cursor at the specified column and row
or position. cursor() places the cursor at the specified col and
row. curs() places the cursor at the position specified by the
int "pos" where the high eight bits of "pos" are the row number
and the low eight bits are the column number. This is the same
encoding returned by get_curs(). In the case of cursor() the
upper left-hand corner of the screen is 0,0, for curs() it is 0.
FUNCTION NAME: get_curs()
get_cursor()
SYNOPSIS: curs_pos = get_curs( void )
int curs_pos; /* current col, row of cursor */
void get_cursor( col, row );
int *col; /* pointer to column variable */
int *row; /* pointer to row variable */
DESCRIPTION:
These functions return the current position of the cursor.
get_curs() returns an integer with the high 8-bits set to the row
number and the low 8-bits set to the Column number. get_cursor()
places the current column and row position into the integer
variables pointed to by col and row.
page 5
FUNCTION NAME: cursor_type()
SYNOPSIS: void cursor_type( curs_num )
int curs_num; /* type code of desired cursor */
DESCRIPTION:
cursor_type() changes the hardware cursor size and shape to one
of nine predefined cursors as selected by the parameter curs_num.
The cursor is smallest when cur_num == 1 and grows steadily
larger until it reaches the size of a full character block at
curs_num == 8. In the special case of curs_num == 0, the cursor
is blanked.
FUNCTION NAME: normal_cursor()
block_cursor()
SYNOPSIS: void normal_cursor( void )
void block_cursor( void )
DESCRIPTION:
These cursor shape control functions set the cursor to
either a normal two bottom scan line cursor or a block
occupying the full character position.
FUNCTION NAME: scroll()
SYNOPSIS: void scroll(u_col,u_row,l_col,l_row,lines,dir,attr);
int u_col; /* upper col */
int u_row; /* upper row */
int l_col; /* lower col */
int l_row; /* lower row */
int lines; /* number of lines to scroll */
int dir; /* direction to scroll */
int attr; /* attribute */
DESCRIPTION:
This function scrolls a region of the screen using the specified
video attribute. Lines refers to the number of lines to scroll.
If "lines" equals zero, then the screen will clear using 'blank'
characters (spaces) with the specified video attribute. The
direction is specified with either 0=up or 1=down.
page 6
Keyboard Functions
FUNCTION NAME: key()
SYNOPSIS: ret_code = key( void );
int ret_code; /* integer return key code */
DESCRIPTION:
Returns the next character in the keystroke buffer. If the buffer
is empty, the routine waits for the next keystroke. If the key is
one of the normal ascii characters, it returns that integer value.
If it is one of the extended keycodes ( function keys, cursor
keys, etc. ), the high eight bits of the return integer contains
the scan code for that key and the low eight bits contain zero.
KEY.H defines integer values to uniquely define most of the keys
on an IBM compatible keyboard.
RETURNS:
An integer key_code.
FUNCTION NAME: shift_stat()
SYNOPSIS: ret_code = shift_stat( void )
int ret_code; /* integer status code */
DESCRIPTION:
keybd_stat() returns and integer value with the current shift
status of the keyboard as reported by the BIOS Get Shift Status
function (INT 16 H, service 2). The status of various keys can
be determined by decoding the individual bits of the returned
integer value as follows.
bit 0 == 1; Right Shift key depressed
bit 1 == 1; Left Shift key depressed
bit 2 == 1; Control key depressed
bit 3 == 1; Alt key depressed
bit 4 == 1; Scroll Lock is active
bit 5 == 1; Num Lock is active
bit 6 == 1; Caps Lock is active
bit 7 == 1; Insert State is active
FUNCTION NAME: char_waiting()
SYNOPSIS: ret_code = char_waiting( void )
int ret_code; /* TRUE or FALSE */
DESCRIPTION:
Returns TRUE (1) if a character is waiting in the keyboard
buffer or FALSE (0) if not.
page 7
Character Output
FUNCTION NAME: write_a()
SYNOPSIS: void write_a(ch,att)
char ch;
int att;
DESCRIPTION:
This function writes a character using a specified video attribute
at the current cursor location. The cursor is not moved.
FUNCTION NAME: write_am()
SYNOPSIS: void write_am(ch,att,count);
char ch;
int att;
int count;
DESCRIPTION:
This function writes multiple characters to the screen with a
specified video attribute. This function is designed to write
characters to the current row only. If the count is greater than
the remaining spaces on that row, the results may be
unpredictable. If the count is 'zero' (0) no characters will be
written.
FUNCTION NAME: write_ac()
SYNOPSIS: void write_ac( ch, att )
char ch;
int att;
DESCRIPTION:
This function writes a character with specified attribute and
advances the cursor one position, wrapping to a new line if
needed. The screen will not scroll, however, and the cursor will
not advance past the last position of line 25.
FUNCTION NAME: write_al()
SYNOPSIS: void write_al(col, row, attr, ch);
int col;
int row;
int attr;
char ch;
DESCRIPTION:
This function writes a character with the specified attribute at
the specified location. The location of the cursor makes no
difference as it is not checked or used by this routine.
page 8
FUNCTION NAME: write_tty()
SYNOPSIS: void write_tty( ch );
char ch;
DESCRIPTION:
This function writes a specified character to the screen using the
bios function "write character as TTY". No attribute is written
with the character, however, the cursor is advanced. This function
recognizes the 'Bell', 'Backspace', 'Return' & 'Line-Feed' ascii
characters.
FUNCTION NAME: write_str()
SYNOPSIS: void write_str(col,row,string,att)
int col,row;
char *string;
int att;
DESCRIPTION:
Writes a string to specified location on the screen using the
specified attribute. The position of the cursor is of no
importance as it is not used or moved by this function. Lines
will wrap to the next line if one is available. The screen will
not scroll at the end of the last line. If you attempt to write
past the end of the last line, those characters are lost.
FUNCTION NAME: print_string()
SYNOPSIS: void print_string( string,att )
char *string;
int att;
DESCRIPTION:
This function prints a string with a given attribute beginning at
the current cursor position. The '\n', '\t', and '\r' characters
are supported. The string wraps at the end of the line and scrolls
at the end of the screen. The cursor is left positioned one
character to the right of the last character in the string.
FUNCTION NAME: aprintf()
SYNOPSIS: void aprintf(att, string, arg(s)...);
DESCRIPTION:
This routine prints a string and expands all arguments, exactly
like printf, and writes the string to the screen starting at the
current cursor position using the supplied attribute "att".
page 9
String Functions
FUNCTION NAME: delete_leading()
del_lead_wht()
SYNOPSIS: void delete_leading(str)
char *str;
void del_lead_wht(str)
char *str;
DESCRIPTION:
These routines remove any leading white space or control
characters from a string. In the case of del_lead_wht() any space
or tab characters are deleted from the front of a string until the
first non space/tab is reached. del_leading() does the same for
any character with an ascii value below 21h.
FUNCTION NAME: delete_trailing()
del_trl_wht()
SYNOPSIS: void delete_trailing(str)
char *str;
void del_trl_wht(str)
char *str;
DESCRIPTION:
These functions remove any white space or control codes from the
end of a string. del_trl_wht() removes any space or tab
characters from the end of a string until a non space/tab is
reached. delete_trailing() does the same for any character below
ascii 21h.
FUNCTION NAME: right_just_str()
SYNOPSIS: void right_just_str(text,outbuffer,width)
char *text;
char *outbuffer;
int width;
DESCRIPTION:
Pads the output string with spaces and copies the text string to
the output buffer so that the end of the text winds up at end of
the output string. If the text string is longer than the
specified width, the text is truncated to fit. The output buffer
must be at least one character longer than "width" to allow for
the null byte at the end of the string.
page 10
FUNCTION NAME: left_just_str()
SYNOPSIS: void left_just_str(text,outbuffer,width)
char *text;
char *outbuffer;
int width;
DESCRIPTION:
Pads spaces to the end of a string to the specified width. If the
string already is as long as or longer than the specified width,
the string is truncated to that width. The output buffer must be
at least one character longer than "width" to allow for the null
byte at the end of the string.
FUNCTION NAME: center_str()
SYNOPSIS: void center_str(text,outbuffer,width)
char *text;
char *outbuffer;
int width;
DESCRIPTION:
Produces a string in "outbuffer" with the specified text string
centered between enough spaces to make the output string length
equal to "width"(excluding the null byte). If the text string
length is longer than the specified width, then the text is
truncated to fill the buffer. The output buffer is assumed to
be long enough to hold the centered string. If the string is to
be centered between an odd number of characters, the extra
character is placed at the end of the string.
FUNCTION NAME: insert_str()
SYNOPSIS: int insert_str( text1, text2, out_buffer, n)
char *text1;
char *text2;
char *out_buffer;
int n;
DESCRIPTION:
Inserts text2 into text1 immediately following the n'th
character of text1, depositing the combined string in
"out_buffer". It is the caller's responsibility to ensure that
the output buffer is large enough. This function returns the
combined length of the result string. If text1 is shorter than
n, text2 is concatenated to text1.
page 11
Video Routines
FUNCTION NAME: vid_type()
SYNOPSIS: ret_code = vid_type( void )
int ret_code;
DESCRIPTION:
This is the routine used to determine the current video
configuration of the machine. It checks the current video mode
to determine if it is 2, 3, or 7. If the current mode is 7
(Monochrome), then the global variables reflecting the present
screen configuration are left set for a monochrome card. If the
mode is 2 (BW80) or 3 (CO80), the variables are set to reflect a
CGA card. The "_color" variable is only set if the current mode
is 3. The function normally returns OK (zero). If any mode other
than 2, 3, or 7 is set, the function returns ERROR (-1).
FUNCTION NAME: save_scn()
SYNOPSIS: void save_scn(ucol, urow, lcol, lrow, buff_address)
int ucol;
int urow;
int lcol;
int lrow;
char *buff_address;
DESCRIPTION:
This routine saves the portion of the screen defined by the
boundary variables to the buffer pointed to by buff_address. No
checking is or can be done to ensure that the buffer is big
enough. vid_type() must be called at least once before calling
this function to properly set the global variables which tell it
where the screen buffer is and whether or not to wait for retrace.
page 12
FUNCTION NAME: rest_scn()
SYNOPSIS: void rest_scn(ucol, urow, lcol, lrow, buff_address)
int ucol;
int urow;
int lcol;
int lrow;
char *buff_address;
DESCRIPTION:
This routine is the opposite of save_scn(). It takes a
previously saved screen image and returns it to the specified
location. As in save_scn, vid_type must be called at least once
before calling this routine.
FUNCTION NAME: video_on()
video_off()
SYNOPSIS: void video_on( void );
void video_off( void );
DESCRIPTION:
These two functions turn the video on and off on a Color Graphics
card to allow writing to the screen without snow. If the mode is
set for a Monochrome card, they simply return and no action is
taken. vid_type() must be called at least once before calling
either of these routines to determine what mode is presently set.
FUNCTION NAME: change_att()
SYNOPSIS: old_att = change_att(col,row,len,att)
int old_att; /* old attribute at start location */
int col; /* start column */
int row; /* start row */
int len; /* number of characters to change */
int att; /* new attribute */
DESCRIPTION:
Changes the video attribute, starting at the specified col and
row, for the number of characters "len". It returns the attribute
byte found at the starting point.
page 13
FUNCTION NAME: h_line()
SYNOPSIS: void h_line(col, row, attr, char, int count);
int col; /* start column */
int row; /* start row */
int attr; /* display attribute */
int char; /* line character */
int count; /* line length */
DESCRIPTION:
Writes multiple copies of the character using the attribute
specified. They will wrap to the next line if necessary. If the
count is zero, no characters are written.
FUNCTION NAME: v_line()
SYNOPSIS: void v_line( col, row, attr, char, number);
int col; /* start column */
int row; /* start row */
int attr; /* display attribute */
int char; /* line character */
int count; /* line length */
DESCRIPTION:
Draws a vertical line starting at col, row, down "number" of
characters using attribute "attr".
FUNCTION NAME: vert_line()
SYNOPSIS: void vert_line(char,attr,count);
int char; /* char to use for vertical line */
int attr; /* display attribute of line */
int count; /* length of line */
DESCRIPTION:
Draws a vertical line starting at the current cursor position,
down the "count" number of characters, using the specified
character and display attribute.
page 14
FUNCTION NAME: shuffle_image()
SYNOPSIS: void shuffle_image(pointer,temp)
WNDW *pointer;
char *temp;
DESCRIPTION:
Takes a pointer to a window and a pointer to a temporary storage
area as arguments. The storage area must be as large as the
window's image buffer. The routine stores the present screen
image at the window location in the window's image buffer and puts
the old contents of the image buffer back on the screen. This
routine is called by activate() to bring an overlaid window to the
top.
FUNCTION NAME: draw_box()
draw_ex_box()
SYNOPSIS: void draw_box(lcol,urow,rcol,lrow,box,linea,filla)
int lcol; /* left column */
int urow; /* upper row */
int rcol; /* right column */
int lrow; /* lower row */
WNDW *box; /* pointer to window structure*/
int linea; /* border video attribute */
int filla; /* fill video attribute */
void draw_ex_box(lcol,urow,rcol,lrow,box,linea,filla,speed)
int lcol; /* left column */
int urow; /* upper row */
int rcol; /* right column */
int lrow; /* lower row */
WNDW *box; /* pointer to window structure*/
int linea; /* border video attribute */
int filla; /* fill video attribute */
int speed; /* exploding box drawing speed*/
DESCRIPTION:
These functions draw a box on the screen. draw_box() simply draws
the box on the screen while draw_ex_box() repetitively draws
bigger and bigger boxes, starting at the apparent center of the
box expanding outwards until the final box size is achieved. No
screen saving is done here. Both routines take as arguments the
upper left and lower right corner cursor locations, the address of
a window structure where the correct characters for the border and
fill can be found, the border attribute and fill character
attribute. draw_ex_box() takes another argument, "speed", which
controls the rate at which the box grows. 0 is the fastest speed,
16000 is the slowest.
page 15
FUNCTION NAME: fill_area()
SYNOPSIS: void fill_area(lcol,urow,rcol,lrow,ch,attr)
int lcol; /* left column */
int urow; /* upper row */
int rcol; /* right column */
int lrow; /* left row */
int ch; /* character to fill */
int attr; /* video attribute */
DESCRIPTION:
Quickly fills the rectangular area of the screen defined by the
parameters with the specified character and video attribute.
FUNCTION NAME: fill_box()
SYNOPSIS: void fill_box(lcol,urow,rcol,lrow,ch,attr)
int lcol; /* left column */
int urow; /* upper row */
int rcol; /* right column */
int lrow; /* left row */
int ch; /* character to fill */
int attr; /* video attribute */
DESCRIPTION:
Much like fill_area() except that fill_box() fills the interior
of the box specified by the bounding rows and columns with any
character and attribute. Please note that the area filled is
inside, not on, the specified rows and columns.
FUNCTION NAME: set_vid_mode()
get_vid_mode()
SYNOPSIS: void set_vid_mode( modenum )
int modenum /* video mode number */
modenum = get_vid_mode( void)
int modenum /* current video mode */
DESCRIPTION:
These routines simply either return the int value of the current
video mode or change it as specified.
page 16
Window Related Functions
FUNCTION NAME: open_window()
open_ex_window()
SYNOPSIS: int open_window(wind)
WNDW *wind;
int open_ex_window(wind,speed)
WNDW *wind;
int speed;
DESCRIPTION:
Takes a pointer to a window structure as an argument and calls
create_window(). They then draw the box on the screen and fill it
using the characters and attributes found in the structure.
In the case of open_ex_window() the box is drawn in an exploding
fashion, starting at the center of the box, growing outward to
it's final size. The speed of the growth is determined by the
variable "speed", with 16,000 being the slowest and 0 the
fastest.
FUNCTION NAME: close_window()
SYNOPSIS: void close_window(wind)
WNDW *wind;
DESCRIPTION:
Closes the window pointed to by "wind". If the window is not the
active window, it is first activated. Finally memory allocated to
it's screen buffer is then freed. Attempting to close a window
that is not open will most likely crash the system. As a matter
of fact, you can count on it!
FUNCTION NAME: clear_window()
SYNOPSIS: void clear_window( void )
DESCRIPTION:
Clears the active window as cls() would do for the entire
screen. The cursor position is not affected, however.
page 17
FUNCTION NAME: activate()
SYNOPSIS: void activate(wind)
WNDW *wind;
DESCRIPTION:
Checks to see if "wind" is currently the active window. If it is
not, it is made the active window, overlying any other windows
which may have been overlaying it. Upon leaving activate_wind(),
the doubly linked list of open_windows is updated so that "wind"
is last and the global "last_wndw" points to it.
FUNCTION NAME: create_window()
SYNOPSIS: ret_code = create_window(new_window)
WNDW *new_window; /* window pointer */
int ret_code; /* OK or ERROR */
DESCRIPTION:
Is called by open_window() or open_ex_window(). It calculates
the size of the image buffer and allocates memory for it. It then
adds the new window to the end of the doubly linked list of open
windows and saves the image at the window position. The
structure variables for image size, image buffer pointer,
previous and next windows are updated here. Nothing is drawn on
the screen in this routine.
RETURNS:
ERROR (-1) if malloc is unable to allocate the storage for the
image buffer, otherwise, OK (zero).
page 18
FUNCTION NAME: title_window()
SYNOPSIS: void title_window(window,string,attr,just_code)
WNDW *window; /* pointer to window */
char *string; /* pointer to title text */
int attr; /* text display attribute*/
int just_code; /* justification code */
DESCRIPTION:
Prints the string to the top of the specified window using the
supplied attribute. The justification code is as follows...
1 == Top-Left; 2 == Top-Center; 3 == Top-Right;
4 == Bottom Left; 5 == Bottom Center; 6 == Bottom Right;
e.g. If the code is ONE, the string is left justified. If it is
TWO, the string is right justified, etc. Strings longer than the
window length minus two characters are truncated. The window is
activated if it is not already active.
FUNCTION NAME: clear_wndw_title()
SYNOPSIS: void clear_wndw_title(window,row)
WNDW *window; /* window pointer */
int row; /* upper or lower row */
DESCRIPTION:
Redraws the top or bottom of the specified window with the default
border chars and attr for that window. The window is activated if
it is not already active. "row" is decoded as follows:
0 == Top-Row;
1 == Bottom-Row;
FUNCTION NAME: scroll_window()
SYNOPSIS: void scroll_window(num,dir)
int num; /* number of lines to scroll */
int dir; /* direction of scroll */
DESCRIPTION:
scrolls the active window "num" lines in direction "dir" where:
dir == 0, scroll up;
dir == 1, scroll down;
page 19
FUNCTION NAME: cursor_window()
SYNOPSIS: void cursor_window(col,row)
int col;
int row;
DESCRIPTION:
Moves the cursor to the specified column and row relative to the
window. 0,0 is the upper left hand corner of the window, just
inside the border. If a row or col argument is specified which is
larger than the number of rows or columns in the window, that row
or column position is set to the maximum value which will keep the
cursor just inside the window border.
FUNCTION NAME: move_window()
SYNOPSIS: void move_window(window,direction,count)
WNDW *window;
int direction;
int count;
DESCRIPTION:
Moves the window "count" spaces in the direction indicated, where
1 = LEFT
2 = UP
3 = RIGHT
4 = DOWN
If the "count" argument is greater than the number of spaces
available on the screen, the window is only moved the number of
spaces where all of the window will still be displayed.
FUNCTION NAME: wprint_string()
wprint_string_att()
SYNOPSIS: void wprint_string( string )
char *string;
void wprint_string_att( string,att )
char *string;
int att;
DESCRIPTION:
wprint_string() writes a string to the currently active window
using that window's fill attribute as it's attribute. Lines wrap
at the window border, and scroll on the last line. The characters
'\n', '\t', and '\r' are supported.
wprint_string_att() is identical, except that the specified
attribute is used instead of the window's fill attribute.
These routines are significantly faster than wprintf()
page 20
FUNCTION NAME: wprintf()
SYNOPSIS: char_num = wprintf( control, arg(s);
char *control;
indeterminate arg(s);
int char_num;
DESCRIPTION:
Formats a printf type string with a variable number of arguments
and writes it to the currently active window. The formatted
sting is stored in a 256 byte global buffer "temp_str". There is
no checking to see if the returned string exceeds this value.
RETURNS:
An integer value set to the number of characters in the formatted
string.
FUNCTION NAME: fprint_window()
SYNOPSIS: void fprint_window(window, text, arg1, ...)
WNDW *window; /* window pointer */
char *text; /* text spring pointer */
indeterminate arg1; /* beginning of argument */
/* list, if any */
DESCRIPTION:
Much like wprintf, except that instead of writing to the
currently active window, any open window can be specified. That
window is then activated if it is not already the active window.
FUNCTION NAME: fill_window()
SYNOPSIS: fill_window( wind_ptr )
WNDW *wind_ptr;
DESCRIPTION:
Quickly fills the interior of the window using the fill character
and fill attribute defined in the window structure.
page 21
Menu Routines
FUNCTION NAME: menu()
SYNOPSIS: ret_val = menu(menu_ptr)
MENU *menu_ptr; /* pointer to menu struct*/
int ret_val; /* OK or ERROR */
DESCRIPTION:
Only one parameter is required to execute a menu, a pointer to a
struct MENU. This structure contains, or points to, all of the
information necessary to open a menu window, make a selection,
then run the appropriate program or routine. Error handling and
context sensitive help are included.
Struct MENU contains pointers to a window structure, a window
title text string, and a screen writing function. It also
contains integer values for default video attributes, a menu
cursor type code, and a window title justification code. These
items define the menu's video display. The function pointers to
help and error functions, and the integer values for the exit and
help hot keys define the menu's behavior. The last two items, a
pointer to the first structure in an array of SEL structures and
the number of SELs in the array, define the individual menu
selections.
Struct SEL contains a pointer to the selection text. The start
column & row where this text will be displayed in the menu window
(the position is referenced to the window, not the full screen).
Integer values for select and unselect attributes if the default
values defined in the MENU structure are not to be used (set to
zero to use the defaults). Integer values for 2 activate keys.
A pointer to a function to be called or a program to be executed
(one of these must be set to a NULL depending on which is not
used). A pointer to a help function (this must be a NULL pointer
if none is provided). Finally an integer which, if zero,
signifies that the menu should be reentered after completion of
the selected routine or program. If non_zero, then the menu is
exited and control passes back to the routine which called it.
whether the return to the menu or the menu's caller should be
executed at the end of the function.
Three types of pseudo cursors are supported. If pcursor_type == 0
then the cursor is as long as the selected text string. If
pcursor_type == 1 then the cursor is as long as the longest text
string in the selection list. If pcursor_type == 2 then the
cursor is as long as the window is wide. All sections functions
must return an integer value.. this value should be zero for a
normal return and any other value for an error condition. This
integer is passed to the menu's user defined error function where
it must be decoded by the programmer. If the error function is
called with a parameter of zero a key stroke error is indicated.
page 22
Calling the menu routine is easy. Setting up all of the
necessary structures and arrays of structures, then stuffing them
with the appropriate values is not. We understand how difficult
and error prone hand coding the menu structures would be, so we
have included in the package MENUGEN.EXE which automates the
process. While using MENUGEN you interactively define the menu
on screen. When complete, MENUGEN writes the control structures
to a file which you then include in your source code. The
operation of MENUGEN is covered more thoroughly in it's own
section.
RETURNS:
An int value. OK (zero) or ERROR ( -1)
Listings of typedef MENU and SEL
typedef struct MENU {
struct WNDW *menu_window; /* Pointer to the menu window structure */
int default_non_select_att;/* Usually the same as window fill attr */
int default_cursor_att; /* Attribute of items when selected */
int title_format; /* Position of menu title on border(1-6)*/
int window_title_att; /* Video attribute of menu title */
char *window_title_text; /* Pointer to menu title text string */
int pcursor_type; /* Type of selection cursor (0-2) */
int exit_key; /* Hot key to exit menu, Usually ESC */
int help_key; /* Hot key to call help function, if any*/
int (*menu_text)(); /* Ptr to function to write text to scrn*/
int (*error_fn)(); /* Ptr to user supplied error handler */
struct SEL *sel_list; /* Ptr to the first in array of SELs */
int num_sel; /* Number of menu selections */
} MENU;
typedef struct SEL{
char *text; /* Pointer to item selection text string */
int start_col; /* Starting col in window for text string */
int start_row; /* Starting row in window for text string */
int sel_att; /* Item sel video attr, Zero for default */
int unsel_att; /* Item unselected video attribute or Zero*/
int activate_key_1; /* First Activate hot key */
int activate_key_2; /* Second Activate hot key */
int (*do_function)(); /* Ptr to selected function or NULL */
char *exe_call; /* Ptr to program name string or NULL */
int (*help_function)(); /* Ptr to optional help fctn or NULL */
int exit; /* exit menu after command, Zero if no */
} SEL;
page 23
Data Entry Functions
FUNCTION NAME: get_field()
SYNOPSIS: ch = get_field(buffer,length,attr,just_code,under_line)
char *buffer; /* pointer to data buffer */
int length; /* maximum length of data */
int attr; /* on screen attribute */
int just_code; /* left(0) or right(1) justify */
int under_line; /* underline(1) field or not(0)*/
int ch; /* last keycode as def in key.h*/
DESCRIPTION:
Gets a string into a data buffer, allowing editing and writing to
the screen using attributes. Left or right justification is
supported. The buffer MUST be length + 1 byte long.
Justification codes are 0 = left, 1 = right. The routine exits
whenever a keystroke with a return code less than 32 (space) or
greater than 256 (as defined in KEY.H) is entered or the cursor
reaches the end of the field.
RETURNS:
It returns a code indicating the last keystroke or a zero if the
end of the field was reached.
FUNCTION: edit_field()
SYNOPSIS: ch = edit_field(buff,length,attr,underline)
char *buff; /* storage buffer */
int length; /* field length */
int attr; /* display attribute*/
int underline; /* underline code */
int ch; /* last keystroke */
DESCRIPTION:
This function is similar to get_field() except that it first
displays at the current cursor position the contents of "buff"
which can then be edited. Only left justification is supported.
RETURNS:
It returns a code indicating the last keystroke or a zero if the
end of the field was reached.
page 24
FUNCTION NAME: update_ins_flag()
SYNOPSIS: void update_ins_flag()
DESCRIPTION:
This function is called each time the insert key is pressed while
in the get_field() data input function. This one is a null routine
which can be replaced by one of your own. This is useful for
doing things like updating an on screen prompt to reflect the
current state of the global insert/overwrite flag "insert_flag".
page 25
INDEX
activate() . . . . . (17) left_just_str() . . (10)
aprintf() . . . . . ( 8) menu() . . . . . . . (21)
block_cursor() . . . ( 5) move_window() . . . (19)
center_str() . . . . (10) normal_cursor() . . ( 5)
change_att() . . . . (12) open_ex_window() . . (16)
char_waiting() . . . ( 6) open_window() . . . (16)
clear_window() . . . (14) print_string() . . . ( 8)
clear_wndw_title() . (18) rest_scn() . . . . . (11)
close_window() . . . (16) right_just_str() . . ( 9)
cls() . . . . . . . ( 4) save_scn() . . . . . (11)
create_window() . . (17) scroll() . . . . . . ( 5)
curs() . . . . . . . ( 4) scroll_window() . . (18)
cursor() . . . . . . ( 4) set_vid_mode() . . . (15)
cursor_window() . . (19) shift_stat() . . . . ( 6)
del_lead_wht() . . . ( 9) shuffle_image() . . (14)
del_trl_wht() . . . ( 9) title_window() . . . (18)
delete_leading() . . ( 9) update_ins_flag() . (24)
delete_trailing() . ( 9) v_line() . . . . . . (13)
draw_box() . . . . . (14) vert_line() . . . . (13)
draw_ex_box() . . . (14) vid_type() . . . . . (11)
edit_field() . . . . (23) video_off() . . . . (12)
fill_area() . . . . (15) video_on() . . . . . (12)
fill_box() . . . . . (15) wprint_string() . . (19)
fill_window() . . . (20) wprint_string_att() (19)
fprint_window() . . (20) wprintf() . . . . . (20)
get_curs() . . . . . ( 4) write_a() . . . . . ( 7)
get_cursor() . . . . ( 4) write_ac() . . . . . ( 7)
get_field() . . . . (23) write_al() . . . . . ( 7)
get_vid_mode() . . . (15) write_am() . . . . . ( 7)
h_line() . . . . . . (12) write_str() . . . . ( 8)
insert_str() . . . . (10) write_tty() . . . . ( 8)
key() . . . . . . . ( 6)
